Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d3 / nyeditme.arc / MANUAL < prev next >

Wrap

Text File | 1987-10-30 | 139.9 KB | 5,301 lines

THE ME TEXT EDITOR (C) COPYRIGHT 1986 MARC ADLER ALL RIGHTS RESERVED MAGMA SOFTWARE SYSTEMS 138-23 HOOVER AVE. JAMAICA, NEW YORK 11435 (718) 793 - 5670 TABLE OF CONTENTS Installing the Editor...................................Chapter 0 Introduction to the ME Editor...........................Chapter 1 The ME Help Facility....................................Chapter 2 Character-Oriented Commands.............................Chapter 3 Line-Oriented Commands..................................Chapter 4 Block Commands..........................................Chapter 5 Input/Output Commands...................................Chapter 6 Searching and Substituting..............................Chapter 7 Keyboard Macros.........................................Chapter 8 Multi-Window Editing....................................Chapter 9 Miscellaneous Commands..................................Chapter 10 Editor Options..........................................Chapter 11 Introduction to the Macro Language......................Chapter 12 Macro Language - Editor Services........................Chapter 13 Macro Language - Buffer Services........................Chapter 14 Macro Language - Primitives.............................Chapter 15 Remapping the Keyboard..................................Appendix A The CTags Utility.......................................Appendix B ME USERS MANUAL INSTALLATION INSTRUCTIONS FOR THE ME EDITOR On the enclosed disk, you will find the editor, help files, macro files, macro compiler, and several other utility files. These files are : INSTALL.BAT - a batch file to perform the installation process ME.EXE - the editor program MACCOMP.EXE - the macro compiler KEYCHART - a table showing the editor commands \HELP\MEHELP.xxx - the editor help files \MACROS\* - the macro source files *.EXM - the macro executable files CONFIG.ME - the editor configuration file MANUAL - the printable documentation for the editor KEYREMAP.ARC - keyboard remapping utilities If you ordered the source code, then there is another disk enclosed which has the source code on it. The executable file is called ME.EXE. This should be placed in one of the directories which is included in your DOS search path, or placed in your current directory. To find out what your current search path is, type "PATH" from the DOS prompt. Refer to the MS/DOS manual if you need help on changing your search path. AUTOMATIC INSTALLATION There is a batch file on the distribution diskette called INSTALL.BAT. Running this batch file will automatically install the editor in the proper subdirectories. This batch file assumes that you have a hard disk drive C:. If you dont, then you can edit the INSTAL.BAT file. You can also follow the instructions contained in the INSTALL.BAT file, and manually install the files. THE ENVIRONMENT VARIABLE During an editing session, the editor may have to look for several files, such as macro files or help files. Normally, the editor first Installing the Editor Chapter 0 Page 1 ME USERS MANUAL searches the current directory, then will search all subdirectories that are listed in your PATH environment variable. To speed up searching, the editor will look for an environment variable called ME. The value of this variable should be the name of a subdirectory which the editor should look in first in order to locate certain files. For instance, if I have a subdirectory called \ME which contains all of the editor's files, then in my AUTOEXEC.BAT file, I might have the statement "set ME=c:\ME". THE CONFIGURATION FILE Among the all of the files is one file which is important (but not required) for configuring your ME editing session. This file is called CONFIG.ME. The CONFIG.ME file should be placed in the subdirectory which you have specified with the ME environment variable. If you don't have this variable, you can put the CONFIG.ME file in any subdirectory along your DOS search path. Although you can alter the values of the parameters in this file without reading the manual, it's recommended that you read the manual and have a little bit of practice with ME before modifying them. Installing the Editor Chapter 0 Page 2 ME USERS MANUAL INTRODUCTION ME (short for Macro Editor) is a programmer's text editor written by a professional programmer for programmers. Although this editor is inexpensive, its power rivals that of much more expensive editors. We strive to keep the editor state-of-the-art and bug-free. If you have any comments at all about the editor, please feel free to contact us. This editor has been written specifically for the IBM Personal Computer, and takes advantage of some of its features, like memory- mapped display, fast string operations, etc. The editor is written mostly in the C programming language, with some assembly language routines to speed things up. The version of C compiler used is Microsoft version 4.0. To run the editor, you need an IBM PC, XT or AT (or compatible), and at least 192K of memory. You should be using DOS 2.0 or greater. The editor uses direct screen writes for speed, and assumes that the video memory for the color card starts at address B800, and the mono card memory starts at B000. If you have an Enhanced Graphics Adapter, the editor's <TOGGLE EGA> command can be used to switch the screen into a 43 line display. All operations on text work extremely fast. All of the data is kept in main memory for speed. With the cost of memory rapidly decreasing, and with the new generation of CPU's which provide virtual memory capabilities, I have seen no need to include virtual memory in the editor. Virtual memory also slows many operations down, such as searching through the entire file for a word. This is because of the disk I/O needed to swap out a section of the file which is not being used any longer, and to swap another section in. FEATURES 1) Powerful C-like macro language for defining your own commands. 2) Remapable keyboard. 3) You may have up to 12 windows shown simultaneously, with a different file in each window. You can also enlarge any window to occupy the whole screen. 4) Regular expression pattern matching. 5) Column block operations. 6) Keyboard macros. 7) Escape to the DOS operating system. 8) 10 "pick" buffers. The ME Editor Chapter 1 Page 1 ME USERS MANUAL RUNNING THE EDITOR You can run the editor from either a floopy disk or a hard disk. If you are using a hard disk, you may want to create a separate subdirectory for all of the editor files, or (most probably) install the editor in a subdirectory which contains most of your executable files. (On my system, I put all the executables in a directory called \bin.) To run the editor, from the DOS prompt type me [options] filename [filename ...] where "filename" is the name of the file you want to edit or create. With DOS, a filename can have up to 8 characters as the main part, and up to 3 characters as the extension. On the DOS command line, you can give the name of more than one file to edit. For instance, when you invoke the editor, you might like to have file "FOO" in the bottom window, and the file "BAR" in the top window. From DOS, you would type the command : me foo bar There is no wildcard expansion for the command line. Be prudent in the number of files you bring up initially, since the editor has no virtual memory capabilities. Pre-loading a Macro If you use the macro facility, there may be times when you would like one or more macro files to be already loaded when the editor starts up. To do this, use the "-l" option. ("l" stands for "load".) Directly after the "l", you must put the name of the executable macro file (without the ".exm" option). As an example, let's assume that you have an executable macro file called "efuncs.exm". To load it in when the editor starts, type the command me -lefuncs foo.c The arguments to "-l" may include a full path specification, like "\e\macros\efuncs". There also may be more than one "-l" argument on the command line, such as me -lefuncs -l\e\macros\c foo.c The ME Editor Chapter 1 Page 2 ME USERS MANUAL EXITING THE EDITOR To exit the editor, press the <EXIT> command. For historical reasons, the <EXIT> command is usually tied to the keystroke <CTRL> D. You are asked if you want to save your changes; type 'y' for yes and 'n' for no. Typing any other key will bring you back into the editor. THE STATUS LINE The 25th line on the IBM PC is reserved for information pertaining to your current editing session. It is also used to display information about various commands, and to receive input from the user for these commands. This line is referred to as the "status line". During your editing session, the status line tells you what column of the line you are on, the current line number, how many lines there are in the file, whether you are in insert or overstrike mode, and the name of the file you are editing. The status line can be distinguished from the rest of the display because it is shown in reverse video. For some commands (like the search and substitute commands), the status line will contain a prompt. You are then required to enter some information on the status line. For most commands, typing the <ESC> key will abort the command. The rightmost part of the status line tells you if NUM LOCK, SCROLL LOCK, and CAPS LOCK is on. The status line will show the letter 'N' if NUM LOCK is on, the letter 'S' if SCROLL LOCK is on, and the letter 'C' if CAPS LOCK is on. CUSTOMIZING THE EDITOR Probably the most powerful feature of the editor is the ability to write macro programs. Many times, you will want to perform a series of complex editing operations that may take many keystrokes. These opera- tions may have to be repeated many times, or may be subject to certain conditions. If this series of operations is something that you need more than once, then it may be beneficial to write a macro to do your task. The ME Editor Chapter 1 Page 3 ME USERS MANUAL For instance, a common operation for C programmers is to take some text and surround it in a comment block. (This was the first macro I wrote.) To do this, you would move the cursor to the first line of the block, and open up a blank line. Then, you would type a slash, and then would fill the rest of the blank line with asterisks. Then you would move the cursor to the beginning of the next line, insert one asterisk, move the cursor to the end of the line, and insert another asterisk. This would have to be done for each line of text inside the block. Then, you would insert a blank line after the last line of the block, and fill the blank line with asterisks, followed by a slash. aaaaaaaa /*********** bbbbbbbb becomes * aaaaaaaa * cccccccc * bbbbbbbb * * cccccccc * ***********/ Since this operation is something that a C programmer does frequently, then this would be a candidate for a macro. The editor comes with a programming language whose syntax resembles the C programming language. Macro programs are written in this lan- guage, then given to the macro compiler to translate into an in- termediate language. This intermediate language can be executed quick- ly by the editor's macro interpreter. When you load a macro into the editor, it is the intermediate language version which is loaded in and executed. When you start the editor, you can indicate which macro files should be loaded in with it. At any time throughout your editing session, you can load in any macro and execute it. The ME Editor Chapter 1 Page 4 ME USERS MANUAL THE HELP FACILITY Among the files that you will find in the ME package are help files. Each help file is called "MEHELP.xx", where xx is a one or two-digit number. It is best to store the help files in a subdirectory called "\ME\HELP". If this is not possible, these files should be stored either in your current directory, or in a directory which is in your DOS search path. When you press the <HELP> command (the ALT H key), ME first looks in a subdirectory called "\ME\HELP". If the help files are not found, ME searches all of the directories in your DOS search path for a file called "MEHELP.0". This file contains the text for the main help menu, and can be changed by you if you want (see below). When ME finds this file, it will display it on the screen, and then prompt you for the help selection. To read a help file, type the number next to the help topic you want to view. ME will then look for a file called "MEHELP.nn" where nn is the number you just typed, and if found, will display the file. After you view this file, ME will re-display the main help screen and prompt you for the next selection. CHANGING THE HELP FILES These help files are in ASCII form, and their contents can be changed by using any text editor available. If you decide to change it, then make sure that you save your changes in ASCII form (especially if you use a word processor which writes out files in their own format). You can add your own help files, as long as you name it "MEHELP.xx", where xx is a one or two-digit number. These new help files should reside in the same directory as the other help files. If you create a new help file, you should add the entry in the help menu found in the file "MEHELP.0". DISCOVERING KEY ASSIGNMENTS The <KEY TO FUNC> function (key ALT F1) will prompt you for a keystroke, and will print out the macro function which that key is associated with, if any. For instance, if after typing <ALT> <F1>, you press <F1>, then the editor will tell you that <F1> is associated with the "delline()" function. Type the <ESC> key to return to the editing session. The ME Help Facility Chapter 2 Page 1 ME USERS MANUAL The ME Help Facility Chapter 2 Page 2 ME USERS MANUAL CHARACTER ORIENTED COMMANDS Normally the editor is in overstrike mode. This means that when you type a character, it replaces the character over the cursor position. The <INS> key toggles the character insert mode on and off. The default mode (unless changed in the CONFIG.ME file) is overstrike mode. Pressing <INS> will change the mode to insert mode. Any charac- ters typed will push the characters beyond it rightwards. When you are in insert mode, the cursor will be block-shaped. On the other hand, when you are in overstrike mode, the cursor will be the the size of the normal DOS cursor. The editor considers all control characters and all extended ASCII characters to be potential commands. This means that all characters whose ASCII values are between 32 and 126 will be inserted into the file as text. To insert the other characters, use the <QUOTE> command. The <QUOTE> command (key <ALT> Q) allows you to insert control characters into your document. After typing the <QUOTE> key, the fol- lowing key you type will have its ASCII value inserted into the text. command below. You may use the <ALT> key in conjunction with the numeric keypad to type in an extended character. Hitting the <RETURN> key has the effect of splitting the current line in two, starting at the cursor position. If you are at the end of the line, then this just has the effect of creating a new line. Although there can be as many as 32,767 characters on one line, please try to limit the number of characters to 256. This should be sufficient for most programming languages. ERASING CHARACTERS The <DEL> key deletes the character under the cursor. If the cur- sor is at the end of a line, then the next line will be joined to the current line. The <BACKSPACE> key deletes the character to the left of the cur- sor. If the cursor is at the left margin, the line will be joined with the previous line. Character Oriented Commands Chapter 3 Page 1 ME USERS MANUAL The <DEL WORD> command (key <SH> <DEL>) deletes the word under the cursor. The <DEL EOL> command (key <SH> KEYPAD 5) deletes all characters from the cursor position to the end of the line. WORDWRAP The editor gives you very basic word processing capabilities by using the wordwrap toggle in conjunction with altering the right mar- gin. The <TOGGLE WORDWRAP> command (the CTRL W key) will toggle wordwrap mode on and off. If wordwrap mode is on, then you will see the letter 'W' on the status line in the "mode" area. To change the right margin, use the <RIGHT MARGIN> command (the ALT M key). You can type in the numerical value of the new right margin. If wordwrap mode is on, and if you type past the right margin, the word will wrap to the next line. 8 BIT MODE All keystrokes which produce a value over 127 are considered by the editor to be commands. If you want to insert an extended ASCII code into your document, you usually use the <QUOTE CHAR> command (the <ALT> Q key). However, there may be times when you wish to insert a sequence of extended ASCII character without having to type <ALT> Q before each one. The <ALT> 7 key toggles between 7 bit mode and 8 bit mode. When you press the <ALT> 7 key to toggle 8 bit mode, the number '8' will appear on the status line in the mode section. This means that 8 bit mode is ON. If you press <ALT> 7 again, the 8 will go away and regular 7 bit mode will be enabled. As long as 8 bit mode is ON, then you can type extended ASCII sequences without having to hit <ALT> Q before each character. To enter an extended ASCII code, you can use the numeric keypad in conjunction with the ALT key, or you may type any function key which produces a character above 127. REMEMBER - all of the editors command will be DISABLED until you toggle back to 7 bit mode. Character Oriented Commands Chapter 3 Page 2 ME USERS MANUAL LINE-ORIENTED COMMANDS Since most programming languages tend to be line oriented, a programmer's text editor should be able to insert, delete, and move lines easily. See the section on block commands to see how to mark and move a series of lines. The <INSERT LINE> command (key F2) inserts a blank line above the cursor. If the auto-indent option is on, then the cursor will move to the column corresponding to the first non-blank character of the previous line. The <APPEND LINE> command (SHIFT F2) will place a blank line below the current line. The <DUPLICATE LINE> command (ALT F9) will duplicate the current line and place the copy on the next line. This is equivalent to press- ing <COPY>, then <DOWN>, then <PUT>. The <DELETE LINE> command (key F1) deletes the line which the cur- sor is on. This command can be preceded by a count (ie - <ESC> 3 <DELETE LINE> deletes 3 lines). The <UNDO> command (key <ALT> U) allows you to restore the last lines or block that was deleted. Buffer 9 is reserved as the place where deleted lines are stored. If you press the <DELETE LINE> command 5 times, then those 5 lines can be restored by using the <UNDO> command. Line Oriented Commands Chapter 4 Page 1 ME USERS MANUAL CUTTING, PASTING, AND BLOCK COMMANDS A "buffer" is a block of memory that holds text. The editor comes equipped with several pre-defined system buffers used to hold "scrap" pieces of text. These buffers are referred to as "pick buffers". The pick buffers are common to all of the windows in the editor. Hence, text that a pick buffer contains can be pasted into any window. There are ten "pick buffers" which you can use to save text when you are cutting and pasting text. The buffers are numbered from 0 to 9, and the default buffer is number 0. To change the number of the current pick buffer, use the <CHG PICK BUFFER> command. This command is initially assigned to the <CTRL> F7 key. The <PICK+CLEAR> command (key F8) clears the current pick buffer, and places the current line in the buffer. The line is then deleted from the file. This command is useful as the first step of moving lines from one location to another. The <PICK+APPEND> command (key <SH> f8) appends the current line to the current pick buffer. The current line is then deleted from the file. The <COPY> command (key <SH> F9) does the same thing as <PICK+CLEAR> except the current line is NOT deleted from the file. All three of the above commands may take an optional count (for example, <ESCAPE> 3 <PICK+CLEAR> will pick and delete the next three lines). There are ten pick buffers, numbered 0 through 9. Buffer 9 has a special use, in that it stores lines and blocks that you have deleted with either the <DELETE LINE> command, or a delete block operation. The <UNDO> command looks in buffer 9 for lines to be reinstated. Buffer 0 is the default buffer. MARKING BLOCKS There are two types of text blocks that you can work with. One kind is a contiguous block, starting at one character and ending at another. The other kind of block is a rectangular block. The command (key F7) defines a block of text to perform an operation on. Move to start of the block and press - a grey rectangle will be shown where you marked the text. Then move to the end of the block and press again. The entire block will be highlighted. You are prompted for the operation to perform on the block. The current operations are pick & clear, pick & append, copy, Working with Blocks Chapter 5 Page 1 ME USERS MANUAL delete, or write to a file. If you want to abort the operation, press either <ESC> or <CTRL> D. The <RECT MARK> command (key <SH> F7) is like the operation, except it defines a rectangular block. This is useful for manipulating columns. If you pick or delete a rectangular block, then you are asked if you want to delete the column or replace the column with blanks. The default is to delete the column. PASTING TEXT The <PUT> command (key F9) allows you to take the contents of the current pick buffer and place it in your text. (Remember that you can change the current pick buffer with the <CHG PICK BUFFER> command.) There are three ways that you can put text back into the file. The first (and most common) way is to INSERT the lines from the pick buffer above the current line. The second method is to insert the text at the current cursor position, pushing the old texst to the right. The third method is to overlay the text, wiping out any text that was there before. The latter two methods are used predominantly with COLUMNS of text. Since most programming languages are line oriented, then the first method of pasting the text is the one that will be used most fre- quently. There is an editor variable which controls whether or not you will be prompted for the method you want when you hit the <PUT> com- mand. This variable, the 'pu' variable in the options menu, is normal- ly off. If the editor detects that the text that resides in the pick buffer was NOT columnar data, and if the 'pu' variable is OFF, then the editor will not prompt you for the pasting method. If the 'pu' variable is ON, then you are asked if you want to in- sert the text above the cursor, insert the text to the right of the cursor, or overlay the text at the cursor position (only if you used a <RECT MARK> to extract a column). These choices are labelled 'i', 'p', and 'o'. The default is to insert the text above the cursor - just hit the <RETURN> key to insert. OPERATIONS ON GROUPS OF LINES Since the structure of computer programs is more oriented towards LINES rather than a STREAM of text, the editor provides operations which you can perform on a disjoint or contiguous set of lines. These operations are the same ones as you find withy the block operations. They are : Working with Blocks Chapter 5 Page 2 ME USERS MANUAL - Delete a group of lines (F1) - Append lines to a pick buffer (SH F8) - Place lines in a pick buffer (erasing the pick buffer first) (F8) - Copy lines into a pick buffer (SH F9) - Write marked lines to a file (ALT W) Normally, all of the above operations operate on a single line at a time (unless preceeded by a count operation). However, if the editor detects that there are marked lines, then the operations are performed on the marked lines. There are three keystrokes used to mark lines. They are : (ALT F7) - marks the current line. The line will be highlighted. (ALT F8) - marks all lines from the current line until the previous marked line. For instance, if you mark line 10, move the cursor to line 15, and press ALT F8, then lines 11 through 15 will be marked. <CLEAR MARKS> (CTRL F8) - this keystroke is usually used to erase a block mark that was previously entered. However, if the editor sees that lines are marked, then the lines will be unmarked. The <DUPLICATE LINE> command (the ALT F9 key) provides a shortcut for copying a group of marked lines to the current cursor position. Mark the lines which you want to make a copy of, and then move the cursor to the line where you would like the copied lines to appear. Press <DUPLICATE LINE>, and the lines will be inserted before the line which the cursor is on. If you are programming in the macro language, then the is_linemarked() primitive is used to tell if the current lie is marked. It returns a zero if the line is not marked, or else it returns a non-zero. Working with Blocks Chapter 5 Page 3 ME USERS MANUAL INPUT/OUTPUT COMMANDS The input and ouput commands support full DOS path names, including a drive specifier. The <READ> command (key <SH> F10) reads a file and inserts the contents before the current line. The file should be an ASCII file, although it may have embedded control characters. The <WRITE> command (key F10) allows you to save the file you are editing to another file. You can print the file by specifying your printer device as the output file. The name of the printer device is usually PRN or LPT1. The <WRITE BUFFER> command (key <ALT> W) does the same thing as <WRITE> but the lines are taken from the current pick buffer (see the help on block commands). If the editor detects that there are marked lines, then the <WRITE BUFFER> command will write the marked lines out to a file. Input/Output Commands Chapter 6 Page 1 ME USERS MANUAL SEARCHING AND SUBSTITUTING The editor allows you to search forwards or backwards through the file for a certain pattern. You can specify whether the search is case insensitive or not. The editor allows you to use a very powerful mechanism called "regular expressions". The use of regular expressions has become very popular since the use of UNIX has become widespread. Although most operating systems let you specify wildcards, UNIX carries the class of expressions further. For a good discussion of regular expressions, please see the book "Software Tools" by Kernigan and Ritchie, published by Addison Wesley. (UNIX is a trademark of AT&T.) The process of searching is done much faster if the editor detects that the pattern you specify does not contain any regular expression metacharacters. The editor uses an assembly language procedure which makes use of the fast 8088 string comparison instructions. When you type one of the search commands, the editor shows you the previous pattern that you typed. If you want to use that pattern again, then just press <RETURN>. METACHARACTERS ? Matches any character * Matches zero or more occurences of the previous pattern. + Matches one or more occurences of the previous pattern. [A-Z] A character class. Matches any character within the class. [^A-Z] Matches any character NOT IN the class. \ Takes the next character literally. ^ Anchors the match at the beginning of the line. $ The match succeeds if at the end of the line. a|b Matches pattern a or pattern b. $a$ Tags pattern a. \n Refers to the tagged pattern n. N is a number from 1 to 9. EXAMPLES abc Matches 'abc'. ^$ Matches a line with no characters. ^abc Matches a line which starts with 'abc'. ^abc$ Matches a line which contains only 'abc'. [A-Z][0-9] Matches a capital letter followed by a digit. [^A-Za-z0-9] Matches a character which is not alphanumeric. Searching and Substituting Chapter 7 Page 1 ME USERS MANUAL be?t Matches 'be', followed by any character, followed by a 't'. (ie - bert, belt, bent). ab*c Matches an 'a', followed by zero or more 'b's, followed by a 'c'. ab\*c Matches 'ab*c'. [A-Z][A-Z]*[.?,! ] Matches a capitalized word. if|else Matches the word 'if' or the word 'else'. if|else|for Matches 'if' or 'else' or 'while'. $abc$[0-9]\1 Matches 'abc', any digit, then 'abc'. $[A-Z]+$?*\1 Matches a line which case two or more occurences of the same upper-case word. You are also allowed to search for a pattern and replace it with some text. The substitution commands prompt you for the search pattern first, and then the text to be substituted. Then, you can specify whether the substitution operation should be done with or without any approval. If you decide to approve each change, then the editor will pause after it has found a match. You are given the option to perform the change ('y'), to ignore the change ('n'), or to quit the substitution operation ('q'). In the substitution text, you may use the metacharacter '&'. This means that you want to use the matched pattern as part of the sub- stitution text. For example, let's say that you specified 'abc' as the pattern to search for. A substitution text of '&xxx' would change 'abc' to 'abcxxx'. Likewise, a substitution text of '12 && 34' would change 'abc' to '12 abcabc 34'. To use a '&' literally in the substitution text, preceed the '&' by a backslash ('\'). In the substitution text, you may also refer to a tagged pattern. For example, let's say that the pattern that you searched for was : $dog$ = $cat$ If you want to replace every occurence of "dog = cat" by "cat = dog", then the substitution pattern that you specify can be : \2 = \1 What this says is that you want the new substitution text to be the first matched pattern ("dog") followed by " = ", followed by the second matched pattern ("cat"). To show a more powerful example, you can have the search pattern : $[a-z]+$->prev = $[a-z]+$; and the substitution pattern : Searching and Substituting Chapter 7 Page 2 ME USERS MANUAL \2->next = \1; The pattern will match a sequence of lower case letters, followed by "->next = ", followed by another sequence of lower case letters, fol- lowed by a semi-colon. The first sequence of lower case letters that is matched is tagged as "\1", and the second sequence of lower case letters is tagged as "\2". This would change the line currentline->prev = newline; to newline->next = currentline; If you need to search for any special control characters, then you can use the <QUOTE> (ALT Q) command. When you press the <QUOTE> key, the next character that you type will be inserted literally in the search string. Searches are normally sensitive to case (ie - upper and lower case letters are different). The <IGNORE CASE> command toggles a flag which allows searches to ignore the case of letters. The key associated with this command is <ALT> F5. Searching and Substituting Chapter 7 Page 3 ME USERS MANUAL KEYBOARD MACROS The editor lets you save a sequence of keystrokes that you type for later use. This is referred to as a "keystroke macro". You can have only one keystroke macro defined at a time. (If popular demand warrants it, we will lift this restriction in future versions.) Keystroke macros are useful if you must perform a tedious sequence of keystrokes over and over. The sequence is so simple that it may not be worth it to write a macro program to do the task. If this is the case, invoke the <CAPTURE> command, type the sequence of keystrokes once, and then press <CAPTURE> again. Your sequence of keystrokes will be saved, and can be replayed by pressing the <REPLAY> key. <CAPTURE> <F4> This function starts the definition of a keyboard macro. All keystrokes that are typed are saved in memory in addition to being sent to the editor. Pressing the <CAPTURE> key again will end the macro definition. See <REPLAY> to see how to recall the keyboard macro. <REPLAY> <F3> This function replays a keyboard macro that was previously defined by the <CAPTURE> function. This command also takes an optional numeric argument, so that <ESC> 5 <REPLAY> will replay the keyboard macro five times. <GENERATE MACRO> <SH> <F3> Occasionally, you may have a keystroke macro that you like so much that you will want to write a macro program which does the same thing. The <GENERATE MACRO> function prompts you for the name which you would like to call this generated macro. You are also prompted for the file name which you would like to APPEND the generated macro to. The editor will then try to generate a macro function in the editor's macro programming language. The generated macro will be APPENDED to the file you specify. The reason for this is because you might have a special macro file which you like to save these little gems in. You should examine the generated macro to make sure that the editor generated the right code. Keystroke Macros Chapter 8 Page 1 ME USERS MANUAL WINDOW COMMANDS A "window" is a view into a buffer of text. Initially, you have one full-screen sized window into your file. There are commands to create and delete windows. Two windows can show different parts of the same buffer. This is useful if you have a long document, and you want to refer to one part of the document while editing another. Of course, different windows can contain different buffers. The editor allows you to have as many as 12 windows visible on the screen. The screen is split horizontally for each of these windows, with each window being approximately the same size. Many times, you would like to expand a window to take up the whole screen. There is a function to enlarge a window so that it takes up the whole screen, and to shrink a window back down and make the other windows visible. You are allowed to transfer text between windows. The 10 pick buf- fers are common to all windows. Any text put into a pick buffer can be pasted into any window. <SPLIT> <ALT> 2 This functions adds another window to the screen. You can have at most 12 windows. Each window is split horizontally, and has ap- proximately the same number of lines. You are prompted for the file name to read into the new window. Type in the name, or press <RETURN> to have a copy of the current buf- fer inserted into the new window. <CLOSE WINDOW> <ALT> 1 or <CTRL> D This function closes the current window (the window which the cur- sor is in). You are asked if you want to save the contents of the file in that window. <ENLARGE WINDOW> <ALT> + This function allows you to expand the current window occupy the entire screen. If there are any other windows, they will remain in- visible until the <SHRINK WINDOW> command is pressed. Editing Multiple Files with Windows Chpater 9 Page 1 ME USERS MANUAL <SHRINK WINDOW> <ALT> - This function makes all windows visible. This is used in conjunc- tion with the <ENLARGE WINDOW> command. <NEXT WINDOW> <PRTSC> This function moves the cursor to the next window on the screen, and makes that window the current window. Editing Multiple Files with Windows Chpater 9 Page 2 ME USERS MANUAL MISCELLANEOUS COMMANDS The <MATCH BRACE> command will find a corresponding curly brace or parenthesis. If the cursor is on a left curly brace or a left paren- thesis, then the editor will search forward for a corresponding right brace or right paren. If the cursor is on a right brace or a right paren, then the editor will search backwards for the corresponding left brace or left paren. If the match is found, then the cursor is placed on the matched character. If no match is found, an error mes- sage will be given. You can set variable length tabs by using the <SET TABS> command. This command is invoked by the <ALT> T key. You will first be prompted to see if you want to clear the previously set tab stops. Then, type in the list of tab stops, each number separated by one or more blanks. For instance, an assembly language programmer may want to set tabs at "10 16 23 35". The <REDRAW SCREEN> command (key <ALT> R) clears the screen and draws a new copy of the text on the screen. This is useful if you are not sure of what's on the screen, or if funny characters appear on your screen due to noise on communication lines. If you have an Enhanced Graphics Adapter, the <TOGGLE EGA> command (CTRL E) will toggle you in and out of 43 line mode. The <OPERATING SYSTEM> command (key <ALT> X) allows you to execute an operating system command from within the editor. Type the command, followed by <RETURN>, and the command will be executed. After the com- mand is finished, you will be brought back to your editing screen. In DOS, you can invoke a secondary command processor by typing "command". You will then "leave" the word processor, and you can interact with DOS. When you want to return to the editing session, type the DOS com- mand "exit". There is another interface to MS-DOS called <DOS CAPTURE>, which is invoked by hitting the <CTRL> X key. This command functions like <OPERATING SYSTEM> command, except that a complete log of your DOS session will be kept. When you exit the command, the captured output will be put in another window. If you want to save this file, you must use the <WRITE FILE> command to save it to another file. (This is be- cause the temporary file that the session is saved in will be deleted automatically.) The <VERSION> (key <ALT> V) command displays the current version number of the editor. Miscellaneous Commands Chapter 10 Page 1 ME USERS MANUAL Miscellaneous Commands Chapter 10 Page 2 ME USERS MANUAL EDITOR VARIABLES There are several variables that are associated with the editor. These variables control some of the behavior of the editor during an editing session. By altering these values, you can further customize your editing session. THE CONFIGURATION FILE Included in the editor package is a file called "CONFIG.ME". This file contains a list of the editor variables and their default values. The meaning of each editor variable is explained below. When the editor starts up, it will try to find the "CONFIG.ME" file. The editor will first search your current directory, and if it's not found there, will search each directory in your DOS search path. If the file is still not found, then the editor will use its built-in default values. There are directions inside the "CONFIG.ME" file for altering the default values. CHANGING THE VARIABLES FROM THE EDITOR You can alter any of the editor variables during your editing session. To do this, use the <OPTIONS> command. The default keystroke for this is <ALT> O. When you press the <OPTIONS> key, the screen will clear, and a list of editor variables will be shown. The name of each variable is shown, followed by its two-character code, followed by its value. To change the value of a variable, type the two-character code followed by a blank, followed by the value. As an example, let's say that you want to disable the auto indent feature. From the options menu, locate the auto indent variable. You see that its two-letter code is "ai". Type "ai n", and hit <RETURN>. You will see that the auto indent variable has changed. To get back to the editing session, press either the <ESC> key or the <CTRL> D key. The new values will take effect when you return from the options menu. The changes remain in effect just until the editing session is over. Configuring the Editor Chapter 11 Page 1 ME USERS MANUAL THE EDITOR VARIABLES Below is a list of the editor variables which are used to control your editing session. After the name of the option is the two character code which you use when you want to change an option. Horizontal Scroll (hs) This variable determines how many columns the screen will scroll leftwards or rightwards when horizontal scrolling is performed. Horizontal scrolling will be initially performed when the cursor moves past the right edge of the current window. The default value of this variable is 40 columns. Vertical Scroll (vs) This parameter controls the number of lines the cursor moves when the <PGUP> and <PGDN> key are pressed. When those two keys are pres- sed, then the value of the VS parameter will be SUBTRACTED from the current window size. The result is the number of lines in the buffer that the cursor will move upwards or downwards. As an example, if you want the cursor to move down only 20 lines when the <PGDN> key is hit, then the VS parameter should have the value 4. In a full screen window, the cursor will move (24 4) = 20 lines. However, in a split screen window, the cursor will move (11-4) = 7 lines. Foreground Color (fg) Background Color (bg) These variables determine the color of the characters (foreground) and the "spaces" (background). These variables only take effect if you have a color card in your PC. Each variable can take on a Talue from 0 to 7. The colors are set according to the standard IBM PC con- ventions. Here is a table of the colors and their associated values : 0 Black (default for background color) 1 Blue 2 Green 3 Cyan 4 Yellow 5 Magenta Configuring the Editor Chapter 11 Page 2 ME USERS MANUAL 6 Brown 7 White (default for foreground color) Increment for tab stops (ta) Controls the distance between tab stops. The default value is 8, which means that tab stops will be set at columns 9, 17, 25, 33, etc. Filler for tabs (tb) When the <TAB> key is pressed, blank spaces will be inserted into the text until the cursor reaches the next tab stop. However, instead of blanks being inserted, you can choose any character as the fill character. This variable takes the ASCII value of the character as its value. The default is the space character, which has ASCII value 32. Automatic Indentation (ai) When a new line is created (by hitting the <RETURN> key or the <INSERT LINE> key), you can specify whether or not the new line should be automatically indented. If this variable has a non-zero value, then the new line will be indented underneath the first non-blank character of the previous line. This feature is especially convenient for programmers who like to indent their code after certain statements. Automatic backup (ab) To help prevent losing your work in case of a system crash, the editor has an option to do automatic backups. If this option is on, then the editor will write out the contents of the current buffer to a "filename.BK2" file periodically. See the option below to change the periodicity. If you finish your editing session successfully, then the backup file will be deleted. Please note that the "BK2" file is different than the ".BAK" file that the editor creates when you save your work. The "BAK" file is just a copy of your old file before the editing session. The "BK2" file is a "snapshot" of your current session made at periodic intervals. Create .BAK file (bk) Configuring the Editor Chapter 11 Page 3 ME USERS MANUAL If this option is OFF, then the editor will NOT create a backup file if you save the current file. The only advantage of turning this option OFF is that you won't clutter your disk with .BAK files. But, we have come to rely on the .BAK files on numerous ocassions. Keystrokes for automatic backup (sv) If the automatic backup feature is enabled, then this variable controls the period between saves, measured in keystrokes. The default is to do an automatic backup once every 1000 keystrokes. You can decrease this amount for more reliability, or increase it if the wait during the automatic backup is annoying. Sound Bell with Prompts (bl) If this parameter is on, then the bell on the PC will sound whenever the editor prompts you for a command. The bell may be annoy- ing to you, depending on how late you're staying up to debug your program. Insert Mode (in) This variable determined whether the editor will be in insert or overstrike mode when the editor starts up. Give this variable a non-zero value if you want insert mode to be the default. Cursor can go into "Free Space" (fs) The term "Free Space" refers to the area after the last character of a line. Some editors refuse to let you move the cursor past the end of a line; if you do, then the cursor usually jumps to either the first character of the next line, or the column immediately after the end of the line. If the Free Space variable is off, then the editor will not let the cursor move into free space. If you type a character in free space, then the area from the last character of the line until the column where the cursor is will be filled with blanks. Prompt user for <PUT> option (pu) If this variable is OFF, and the text that is in the pick buffer was not put in there by a columnar block operation, then the editor will not prompt you when you <PUT> the text. (Key F9). Otherwise, the editor will ask you if you want to insert the text above the current line, push the text before the cursor position, or overlay the text. Configuring the Editor Chapter 11 Page 4 ME USERS MANUAL Wait for acknowledgement of an error (er) If this variable is ON, then the user must hit a key after an error message is printed on the status line. If this variable is OFF, then the error message will be printed, but the user can go right on typing commands. Strip high bits when reading a file (hb) Some word processors use a special encoding where they set the high bit ON on some of the characters. If this option is ON, then each character that is read in will have its high bit turned OFF. Convert blanks to tabs (bt) In order to save disk space, you may choose to compress sequences of blanks to tabs when the file is saved. The default value is OFF, so your output file will contain no tabs. Snow on CGA? (ns) Many Color Graphics Adapters require you to wait for horizontal retrace before writing a character to the screen. However, certain CGAs do not require the waiting period. If your CGA does not require a wait, turn this option OFF (ie - there is NO snow). Configuring the Editor Chapter 11 Page 5 ME USERS MANUAL THE MACRO LANGUAGE Even though the editor is a very powerful tool for text manipulation, sometimes you find yourself wishing for commands that the editor does not provide. Therefore, the editor provides a facility for you to write your own editing commands. These commands are called "macros". The macro language that the editor comes with resembles the programming language called "C". Although the macro language is a far cry from the complete C language, the syntax of the statements closely resembles that of C. COMPILING A MACRO A macro file can contain several macros. The macro file must be compiled with the macro compiler (maccomp.exe). If the compile is successful, then the compiled macro will be written out to a file with the same "root" name, but with the extension ".EXM". Then the ex- ecutable version of the macro (macro.exm) should be loaded into the editor when you want to use it. To load a macro into the editor, you can 1) use the <ALT> P key and specify the name of the macro. This will load but NOT execute the macro. See below for directions on how to execute a macro. 2) use the -l option on the command line, and give the name of the macro file after the "l". Example - "me -lisrch foo.c". EXECUTING A MACRO In order to execute a macro, the macro must be loaded into the editor by either one of the two methods mentioned above. Once a macro is loaded, you can press the <ALT> P key, and give the name of the macro to execute. Additionally, you can make any keystroke invoke a macro. To do this, use the <ASSIGN KEY> command (the ALT F4 key). You are asked for the name of the macro to invoke, and for the keystroke which invokes it. Introduction to the Macro Language Chapter 12 Page 1 ME USERS MANUAL You can bind a keystroke to a macro by using the assign_key() function in the macro. You should define the key assignment in the macro's init() procedure (see the end of this chapter). DATA TYPES The macro language supports two data types - integer and string. An integer is a whole number between -32,767 and +32,767. A string is a sequence of 1 or more characters, ended by the NULL character (ASCII value 0). In the macro language, the word "int" is used to declare variables as type integer. The word "string" is used to declare string variables. If you are a C programmer, be careful not to slip up and declare string variables as "char *". CONSTANTS An integer is a sequence of digits, preceded by an optional negative sign. A single character can be referred to by enclosing it in single quotes. Characters will be converted internally to an integer representing the ASCII value of the character. You can represent non-printable characters and non-ASCII characters by enclosing between the single quotes a backslash, followed by up to 3 digits. For instance, '\07' represents the character CTRL-G (ASCII value 7), and '\233' represents the value 233. Notice that the written number is decimal (not octal). Several popular control characters can be expressed by a backslash, followed by a letter. Here is a list of those characters. '\b' backspace '\n' newline '\E' escape '\'' single quote '\\' backslash A string is a sequence of characters enclosed in double quotes. Internally, each string is ended by an invisible NULL character (ASCII value 0). You do not have to write the NULL character - its prescence is implied by the definition of a string. However, if you are examining the string by looking at a character at a time, you can test the current character to see if it's 0. Introduction to the Macro Language Chapter 12 Page 2 ME USERS MANUAL Any character in the string can be one of the control characters mentioned above. OPERATORS Arithmetic operators + addition - subtraction or unary minus * multiplication / division % modulo (remainder) As in most programming languages, multiplication and division take precedence over addition and subtraction. Auto increment and decrement are supported, as are certain aug- mented operators. You can have the constructs ++x, x++, --x, x-- x += y, x -= y, x *= y, x /= y, x %= y Relational operators < less than <= less than or equal > greater than >= greater than or equal == equal != not equal Relational operators have equal precedence. Relational expressions evaluate to 1 if true and to 0 if false. The relational operators can be applied to both data types, integer and string. (Note to C program- mers - there is no strcmp() function you can use the relational operators to compare strings). Logical operators && and || or ! not Introduction to the Macro Language Chapter 12 Page 3 ME USERS MANUAL NOT has the highest precedence, followed by AND, and then OR. CONVERSIONS While the macro program is executing, the interpreter will attempt to perform conversions of data types to prevent the macro programs from bombing. COMPILER DIRECTIVES The macro compiler can accept the directives #define and #include. The #define resembles the #define directive used in the C prepreces- sor. The #define directive takes a word and a string it should be replaced by. At this point, you cannot have macro functions defined (ie you cannot have something like "#define sqr(x) ((x)*(x))" yet). example of #define #define CTRL_C 3 assign_key("center", CTRL_C); The macro language has an #include directive which allows you to include files for compilation. The syntax is : #include filename As an example, #include srchmark (Note - filename should NOT be in quotes NOR in angle brackets like in C). STATEMENTS Each statement must be ended by a semi-colon (';'). There is no limit on the number of statements on one line, or the column in which a statement begins. The macro compiler is insensitive to white space. LIST OF STATEMENTS Introduction to the Macro Language Chapter 12 Page 4 ME USERS MANUAL Assignment variable = value; This statement is used to put a certain value into the variable on the left hand side of the '=' sign. The value can be any expression, which can be comprised of other variables, constants, and operators. Examples : int n; string s; n = 3; n = n * 5 + strlen(str); s = "This is a message"; If statement if (condition) stmt; if (condition) stmt; else stmt; The condition inside the parentheses is evaluated, and tested for a non-zero value. If the result is non-zero, then the statement after the if (the "then" portion) will be executed. If the result was zero, then the "else" portion will be executed. Each 'stmt' can be a group of statements. This is often referred to as a "block statement". In this macro language, a block statement must start with a left curly brace ('{') and must end with a right curly brace ('}'). As an example, if (x == 1) { y = 2 * y; insert(itoa(y)); } else { Introduction to the Macro Language Chapter 12 Page 5 ME USERS MANUAL x = x - 1; y = 3; } The curly braces may occur on the same line as the "if" and the "else" parts. The style of indenting is up to you. While statement while (condition) stmt; The statement inside the 'while' will be executed continuously un- til the condition is found to be zero. Example : while (!is_eol()) { if (currchar() == 'x') delchar(); else right(); } For statement for (initial statement; condition; increment) stmt; This is equivalent to initial statement; while (condition) { stmt; increment; } The for statement is a more convenient way to do looping than the while statement if the loop involves counting from one value to another. Introduction to the Macro Language Chapter 12 Page 6 ME USERS MANUAL Break statement break; The break statement is used to exit from the inner most loop. If there is only one loop, then the loop is exited. Example while (x < 13) { .... for (i = 1; i <= len; i = i + 1) { ...... if (x < 0) break; /* go to the "x = x+1" statement */ ...... } x = x + 1; } Function calls function_name ([arg1, arg2, ..., argn]); You can call any primitive function, any built-in macro, or any macro which you define. The calling function can pass arguments to the called routine. Each argument in the argument list is an expression which is evaluated, and then whose result is passed down to the call- ing routines. Arguments are passed by value, not by reference. Examples : justify_line(); if (is_string_numeric(str)) ...... n = strlen(str1) + strlen(n2); Return statement Introduction to the Macro Language Chapter 12 Page 7 ME USERS MANUAL return; return expression; A return statement is used to terminate a macro and return to the calling macro, if any. An optional value may be returned by the macro. The return expression may be of type integer or type string. Since there is no type associated with a macro, one return statement may return a string while another may return an integer. COMMENTS Any text that falls between "/*" (comment begin sequence) and "*/" (comment end sequence) will be ignored by the macro compiler, and will be treated as a comment. A comment may be placed on a line by it- self, or may be placed after a statement. A comment can also span several lines. THE LAYOUT OF A MACRO FILE A macro file looks like this : [optional global variable declarations] macro1 defintion [optional globals - seen only by macros 2-n] macro2 defintion ................ macro n definition GLOBAL VARIABLES Any global variables that you use should be declared at the top of the macro file. These variables may be accessed by any macro in the macro file. You can also declare globals in between two macro definitions (ie - after the right curly brace which ends a macro). These global definitions are only seen by the macros which come physically AFTER these globals in the file. Introduction to the Macro Language Chapter 12 Page 8 ME USERS MANUAL LOCAL VARIABLES Local variables are variables which can only be used within the macro which they are declared in. These include the parameters which are passed to a macro. If a variable is used inside a macro, and has not been declared, then the macro interpreter will declare it automatically, and will try to determine its data type from the context in which it's used. The default type is integer. DEFINING A MACRO There can be as multiple macros defined in one macro file. Each macro definition has the following form : macro-name ([parameters]) [parameter declarations] { [local variable declarations] statements } The first line is a header that contains the name of the macro, and an optional list of parameters. The macro name must start with a letter or an underscore ('_'). The parentheses must follow the macro name, even if there are no parameters. If the macro has parameters, then the parameter declarations should follow. The declarations give the type and name of each parameter. The parameters can either be integer or string. If a declaration for a parameter is left out, then the parameter is assumed to be of type integer. After the optional parameter declarations, a left curly brace must follow. Any local variables that the macro uses should be declared now. Then comes the list of statement that comprise the body of the macro. The right curly brace ends the entire macro. If you are a C programmer, you may be used to declaring the type of the function, whether it be an integer function or a function returning a pointer. In this macro language, there are no type declarations associated with macros. The type of value that a macro returns (if any) is determined by the RETURN statement. Introduction to the Macro Language Chapter 12 Page 9 ME USERS MANUAL As a detailed example of a macro, let's consider writing a macro that determines if a string contains all digits. The name of this macro will be "is_string_numeric". This macro, which should be called by another macro, takes one parameter - the string to examine. This macro should return 1 if the string is all numeric, and 0 if not. A loop is used to traverse the string, one character at a time. To extract the character at the ith position, we use the built-in function substr(). The first argument to substr() is the name of the string to examine, the second argument is the starting position to look at, and the thrid argument is the number of characters to extract. Substr() returns a string result. The character is then tested to see if it falls outside the range of "0" to "9". If it does, then that means that a non-numeric character was found, and 0 is returned. If the loop ends, that means that all the characters were numeric. The second return statement is executed, and 1 is returned to the calling macro. is_string_numeric(str) /* macro definition */ string str; /* parameters */ { string c; /* local variables */ int i, len; len = strlen(str); /* get the number of characters in str */ /* The for loop is used to walk through the string, one character at * a time. Notice that the ith character of a string occurs at * position i. (Not at position i-1, like in C.) */ for (i = 1; i <= len; i = i + 1) { c = substr(str, i, 1); /* c is the character at position i */ if (c < "0" || c > "9") /* test if c is not numeric */ return(0); /* NO!!! */ } return(1); /* A positive return value means that it's numeric */ } Introduction to the Macro Language Chapter 12 Page 10 ME USERS MANUAL THE INIT() MACRO When a macro file is loaded into the editor for the first time (by the <LOAD MACRO> command or by the -lmacname option on the command line), the editor looks for a macro called init(). If this macro is defined in the macro file, then the editor will execute this macro once and only once when the macro file is first loaded. The kind of things that you might put in the init() macro would be key assignments, opening messages, and initialization of global variables. See the assign_key() primitive for information on how to make key assignments. Introduction to the Macro Language Chapter 12 Page 11 ME USERS MANUAL THE EDITOR COMMANDS The editor functions are available as a keystroke and/or as a function which can be called from a macro program. In the following list of commands, the function name (if there is one) is specified first, and the default keystroke (if there is one) is specified next. The keystroke name is enclosed between "<" and ">". A normal function key is designated as <F1-10>, a shifted function key is designated at <SH> <F1-10>, a CTRL function key is designated as <CTRL> <F1-10>, and an ALT function key is designated as <ALT> <F1-10>. NUMERIC ARGUMENTS Various commands can take an optional numeric argument. This number specified the number of times to perform that command. To specify a numeric argument, type the <ESCAPE> key, followed by the number, followed directly by the command key. (Do not type a <RETURN> after the last digit of the number!) CURSOR MOVEMENT COMMANDS up() <UP ARROW> This function moves the cursor up one line. If the "GOFREESPACE" parameter is zero, and the cursor lands past the end of the new line, then the cursor will be moved to just past the last character of the line. Up() returns 1 if the move was successful, and 0 if not. down() <DOWN ARROW> This function moves the cursor down one line. If the "GOFREESPACE" parameter is zero, and the cursor is past the end of the line, then the cursor will be moved to just past the last character of the line. Down() returns 1 if the move was successful, and 0 if not. left() <LEFT ARROW> This function moves the cursor left one character. If the cursor is at the beginning of a line, then the cursor will move to just past the last character of the previous line. Left() returns 1 if successful, and 0 if not. Macro Functions - Editor Services Chapter 13 Page 1 ME USERS MANUAL right() <RIGHT ARROW> This function moves the cursor right one column. If the "GOFREESPACE" parameter is zero, and the cursor is past the end of the line, then the cursor will be moved to the first character of the next line. Right() returns 1 if the move was successful, and 0 if not. nextword() <CTRL> <RIGHT ARROW> This function moves the cursor to the next word in the file. If successful, nextword() returns 1, else returns 0. prevword() <CTRL> <LEFT ARROW> This function moves the cursor to the previous word in the file. If successful, prevword() returns 1, else returns 0. nextpara() <CTRL> <PGDN> This function moves the cursor to the next paragraph in the file. If successful, nextpara() returns 1, else returns 0. A paragraph is defined as the first line after one or more blank lines. The cursor is positioned at the first non-blank character of the new paragraph. prevpara() <CTRL> <PGUP> This function moves the cursor to the previous paragraph in the file. If successful, prevpara() returns 1, else returns 0. The cursor is positioned on the first non-blank character of the new paragraph. goline(n) <ALT> G int n; # the line number to go to Goline() allows you to jump to any line in the file. When this command is invoked from the keyboard, you are allowed to enter an absolute line number (3, 421), an amount relative to the current line (-23, +4), or an amount relative to the last line in the file ($, $-9). If you enter the letter 'a' through 'z', then the corresponding bookmark will be jumped to (see bookmark()). gobof() <SH> <PGUP> This function moves the cursor to the first line of the file. gobol() <HOME> Macro Functions - Editor Services Chapter 13 Page 2 ME USERS MANUAL This function moves the cursor to column 1 on the current line. goeol() <END> This function moves the cursor to one column beyond the last character in the current line. goeof() <SH> <PGDN> This function moves the cursor to just after the last character of the file. nextscreen() <PGDN> This function scrolls the current window down by the number of lines in the window. prevscreen() <PGUP> This function scrolls the current window up by the number of lines in the window. home() <CTRL> <HOME> This function moves the cursor to the top left corner of the current window. bottom() <CTRL> <END> This function moves the cursor to the lower left corner of the current window. DELETION COMMANDS backspace() <BACKSPACE> This function deletes the character to the left of the cursor. If the cursor is at the beginning of a line, then the current line will be joined to the end of the previous line. delchar() <DEL> This function deletes the character under the cursor. If the cursor is past the last character of the line, then the next line is joined with the current line. Macro Functions - Editor Services Chapter 13 Page 3 ME USERS MANUAL deleol() <SH> <NUMERIC 5> This function deletes all characters from the current cursor position until the end of the current line. delline() <F1> This function deletes the current line. It may be preceeded by a com- mand count. However, if the editor sees that there are marked lines, then delline() will be performed on the marked lines. delword() <SH> <DEL> This function deletes the next word. If the cursor is in the middle of a word, then the whole word is still deleted. INSERTION COMMANDS <INS> This keystroke toggles the editor between insert mode and overwrite mode. When insert mode is enabled, then a character that you type will push the remaining characters on the line over by one column. When overwrite mode is on, then the character that you type will replace the old character at the cursor position. On the status line, the mode is indicated by an 'I' for insert mode and an 'O' for overwrite mode. Also, the cursor is a full block when in insert mode, and an underscore when in overwrite mode. Insert mode is always on when a macro program is being executed. insline() <F2> This function inserts a blank line before the current line. CUT AND PASTE COMMANDS The first three commands deal with only the current line (unless preceeded by the optional numeric argument). However, if the editor sees that there are marked lines, then these commands will be performed on the marked lines. Macro Functions - Editor Services Chapter 13 Page 4 ME USERS MANUAL cut() <F8> This functions clears the current pick buffer, then copies the current line into it. The current line is then deleted. This function can take an optional numeric argument. cut_append() <SH> <F8> This function performs the same operation as above, except that the current pick buffer is NOT cleared first. The current line will be appended onto the end of the pick buffer. copy() <SH> <F9> This function copies the current line into the current pick buffer. Copy() can take an optional numeric argument. paste() <F9> This function inserts the lines contained in the current pick buffer above the current line. If the inserted lines start at whatever column the cursor is currently at. This function can take a numeric argument. BLOCK COMMANDS mark() <F7> This function places a mark at the cursor location. If this is the first time the marker was set for this block, nothing happens. If this is the second time, the block will be highlighted. colmark() <SH> <F7> This function places a columnar mark at the cursor location. When this mark is set for the second time, then a rectangular region is defined. The top left and bottom right corners are defined by the two marks. markline() <ALT> <F7> This function will mark the current line. You can mark any number of lines, and the series of lines which are marked can be disjoint or contiguous. If the editor detects that lines are marked, then the Macro Functions - Editor Services Chapter 13 Page 5 ME USERS MANUAL delline(), cut(), cut_append(), copy(), and write_pick() commands work on the marked lines instead of the current line. markgroup() <ALT> <F8> This function searches backwards for the last line that was marked, and marks all lines from the currentline until the last marked line. If no marked lines are found, then the current line is marked. clear_mark() <CTRL> <F8> This function clears out any marks, if any exists. This works on both block marks and line marks. set_picknum(n) <CTRL> <F7> int n; Changes the current pick buffer to the number you choose. The pick buffers are numbered from 0 to 9, with buffer 0 as the default. SEARCH & SUBSTITUTE COMMANDS fsearch(pattern) <F5> string pattern; Searches through the buffer for the regular expression "pattern". The pattern may be any regular expression. If found, then the current line is set to the line that contains the first match, and the cursor is positioned at the match. Search() returns the column number of the match (greater than 0) if it succeeds, and 0 if it doesn't. rsearch(pattern) <SH> <F5> string pattern; This function is similar to the fsearch() function, except that the file is searched backwards starting from the previous line. fsubst(pattern, subtext, approval) <F6> string pattern, subtext; int approval; Macro Functions - Editor Services Chapter 13 Page 6 ME USERS MANUAL This function searches for the first occurence of pattern, and substitutes subtext in its place. The direction for the search is forwards. 'Approval' should be 0 if the substitution should be global, or non-zero if you want the user to approve each change. Fsubst() returns 1 if successful, and 0 if not. rsubst(pattern, subtext, approval) <SH> <F6> string pattern, subtext; int approval; Rsubst() is similar to fsubst(), except the direction for the search is backwards through the file. ignore_case(value) <ALT> <F5> int value; Allows you to toggle the case-ignore flag. When executing this function from a macro, it will SET the case-ignore flag if the value parameter is 1. Otherwise, it will RESET the flag. INPUT/OUTPUT COMMANDS readfile(filename) <SH> <F10> string filename; This function reads the file "filename" into the buffer BEFORE the current line. Returns 1 if successful, and 0 if not. The filename may be a full path name, including drive designator. writefile(filename) <F10> string filename; This function write the current buffer out to the file named "filename". Returns 1 if successful, 0 if not. The filename may be a full path name, including drive designator. writepick(filename) <ALT> W string filename; This function write the contents of the current pick buffer to the named file. If there are marked lines, then the marked lines will be written to the named file. Macro Functions - Editor Services Chapter 13 Page 7 ME USERS MANUAL WINDOW COMMANDS The editor allows you to have as many as 6 windows visible on the screen. The screen is split horizontally for each of these windows, with each window being approximately the same size. Many times, you would like to expand a window to take up the whole screen. There is a function to enlarge a window so that it takes up the whole screen, and to shrink a window back down and make the other windows visible. You are allowed to transfer text between windows. The 10 pick buffers are common to all windows. Any text put into a pick buffer can be pasted into any window. <SPLIT> <ALT> 2 This functions adds another window to the screen. You can have at most six windows. Each window is split horizontally, and has approximately the same number of lines. You are prompted for the file name to read into the new window. Type in the name, or press <RETURN> to have a copy of the current window inserted into the new window. <CLOSE WINDOW> <ALT> 1 or <CTRL> D This function closes the current window (the window which the cursor is in). You are asked if you want to save the contents of the file in that window. <ENLARGE WINDOW> <ALT> + This function allows you to make the current window occupy the entire screen. If there are any other windows, they will remain invisible until the <SHRINK WINDOW> command is pressed. <SHRINK WINDOW> <ALT> - This function makes all windows visible. This is used in conjunction with the <ENLARGE WINDOW> command. <NEXT WINDOW> <PRTSC> This function makes the next window the current window, and moves the cursor there. Macro Functions - Editor Services Chapter 13 Page 8 ME USERS MANUAL KEYBOARD MACROS <CAPTURE> <F4> This function starts the definition of a keyboard macro. All keystrokes that are typed are saved in memory, in addition to being sent to the editor. Pressing the <CAPTURE> key again will end the macro definition. See <REPLAY> to see how to recall the keyboard macro. <REPLAY> <F3> This function replays a keyboard macro that was previously defined by the <CAPTURE> function. This command also takes an optional numeric argument, so that <ESC> 5 <REPLAY> will replay the keyboard macro five times. MACRO PROGRAMS When typed from the keyboard, <ALT> P will prompt you for a macro name. If the macro is not already loaded, then the name you type is considered to be an executable ".exm" file. The editor will load, but not execute that macro. On the other hand, if the editor detects that the macro is loaded, then it will execute that macro. In this case, <ALT> P may be preceeded by an optional numeric argument. loadmacro(macrofile) <ALT> P string macrofile; This function loads the macro file "macrofile" into the editor. There must be an executable version of the macro called "macrofile.exm". Returns 1 if the loading succeeded, and 0 if not. domacro(macroname) <ALT> P string macroname; This function executes the (previously loaded) macro named "macroname". MISCELLANEOUS COMMANDS <QUOTE> <ALT> Q This allows you to insert a control character into the text at the cursor location. A control character is defined as a character whose ASCII value is less than 32 or greater than 126. On the IBM PC, this character will usually be represented as a graphic symbol. Macro Functions - Editor Services Chapter 13 Page 9 ME USERS MANUAL When you press the <QUOTE> key, the prompt on the status line says "QUOTE". The character you press next will be inserted at the cursor position. You can use the ALT key in conjunction with the numeric keypad to insert characters above 126. <HELP> <ALT> H This function calls the editor help routine. <OPTIONS> <ALT> O This function brings up the options menu. The options menu contains the names of important editor variables and their values. To change a value, type the two-letter code for the parameter, a space, and the value. Typing <CTRL> D or <ESC> will return you to the editor. See the section on the editor variables for more information. undo() <ALT> U This function restores the last deleted line or block. Deleted lines and blocks are saved in a special system buffer. The undo() function inserts this buffer before the current line. <TEST KEYS> <ALT> <F10> This function prompts you for a keystroke, and prints out the key value for that keystroke. The key value is the decimal value as- sociated with the keystroke. For values less than 127, it's the ASCII code. For values above 127, it's (usually) the scan code plus 128. This can be used with the assign_key() primitive or the <ASSIGN KEY> command to see what value a keystroke is associated with. <ASSIGN KEY> <ALT> <F4> This function prompts you for a macro name (which has already been loaded), and asks you what keystroke it should be bound to. To use the <ASSIGN KEY> function in the macro language, see the assign_key() primitive. <TAB> <TAB> This function inserts spaces until a tabstop is reached. The tab fill character is initially a space (ASCII 32), but can be changed in the options menu. Macro Functions - Editor Services Chapter 13 Page 10 ME USERS MANUAL os_command(cmd) <ALT> X string cmd; This function calls the DOS command interpreter to perform one com- mand. The string 'cmd' contains the command to execute. 'Cmd' can be the string "command" if you want to enter the command interpreter for an extended period of time. To get back to the editor, type the DOS command "exit" at the DOS prompt. This function returns the error code sent by the executed command. An error code of 0 usually means successful completion. refresh() <ALT> R This function redraws the screen. It's used if the screen happends to get messed up by "noise" over transmission lines, or if someone writes a message to your tty. bookmark(ch) <ALT> B int ch; This function sets a "place marker" at the current line and current column. This marker is named with letters 'a' through 'z'. You can have as many as 26 different place markers set at one time. Macro Functions - Editor Services Chapter 13 Page 11 ME USERS MANUAL BUFFERS AND THE MACRO LANGUAGE A "buffer" is an area which holds text. Each buffer has a name as- sociated with it, which is usually the name of the file where the text originated from. A buffer may be shown in a window on the screen, or may be invisible (ie the editor's "pick buffers" are invisible). A buffer may be shown in one window, or in multiple windows. The editor keeps a list of buffers which are currently in ex- istence. This list can be envisioned as a circular list - the buffer that comes after the last buffer is the first buffer. The editor operations always deal with the currently active buffer. Each buffer contains a unique identifier. The identifier is an in- teger which starts at 1. Most of the buffer functions take an iden- tifier as an argument. You can always find out the identifier of a buffer by using the find_buffer() function. The macro language contains functions which can manipulate buffers. These functions DO NOT have any associated keystrokes - they are only available through macros. BUFFER FUNCTIONS create_buffer(filename) string filename; DESCRIPTION Create_buffer() will create a brand new buffer and attach it to the buffer list. The filename should be the name of the file that the buffer is associated with. The editor will search for a file with that name, and attempt to read the file into the new buffer. If there is no file by that name, then the buffer will initially contain a blank line. It is important to note that the new buffer WILL NOT become the current buffer unless you use the setcurrbuf() function or the show_buffer() function. ARGUMENTS 'Filename' is the name of the file that is associated with the new buffer. Macro Functions - Buffer Services Chapter 14 Page 1 ME USERS MANUAL RETURNS If successful, the ID of the new buffer will be returned. The ID is an integer greater than 0. If not successful, returns 0. EXAMPLE # The following code tells DOS to do a directory listing and put # the output into a file called "foo". If this was successful, then # we will create a new buffer and read "foo" into it. If this was # successful, we will make the new buffer the current buffer, and # show it. int id; if (os_command("dir > foo") && (id = create_buffer("foo")) > 0) show_buffer(id); currbuf() DESCRIPTION Currbuf() returns the ID of the current buffer. ARGUMENTS None. RETURNS The ID of the current buffer, if one exists. The ID is an integer greater than 0. If no buffer exists, then 0 is returned. EXAMPLE # See if we already have a buffer associated with the file foo.c. If # so, then set the current focus to that buffer. If invisible, the # buffer will remain invisible. int id; id = find_buffer("foo.c"); if (id > 0) setcurrbuf(id); Macro Functions - Buffer Services Chapter 14 Page 2 ME USERS MANUAL delete_buffer(id) int id; DESCRIPTION Delete_buffer() removes the buffer whose identifier is ID. The buffer is deleted from the buffer list, and any windows associated with that buffer will be deleted. This function does not set the new current buffer, nor the new current window. This function should be used with extreme caution. If you delete the current buffer, and then try to do editing operations without set- ting the new current buffer, chaos may result. ARGUMENTS The identifier of the buffer to delete. RETURNS Returns 1 if successful, 0 if not. EXAMPLE # This code deletes the buffer associated with file "foo.c". int currid, id; currid = currbuf(); id = find_buffer("foo.c"); if (id > 0) delete_buffer(id); if (currid == id) # watch out!!! We deleted the current buf show_buffer(next_buffer(id)); # set the new buffer find_buffer(name) string name; DESCRIPTION Find_buffer() searches for a buffer named "name", and returns the identifier associated with that buffer. Macro Functions - Buffer Services Chapter 14 Page 3 ME USERS MANUAL ARGUMENTS The name of the buffer to be located. RETURNS The ID of the buffer is returned if the buffer was found. If not, 0 is returned. EXAMPLE int id; if ((id = find_buffer("foo.c")) > 0) show_buffer(id); next_buffer(id) int id; DESCRIPTION Next_buffer() returns the identifier of the next buffer in the buffer list. The buffer list is circular, so the next buffer after the last buffer is the first buffer. ARGUMENTS 'Id' is the identifier of the buffer to start at. RETURNS The identifier of the buffer AFTER the buffer with identifier 'id'. f there are no buffers associated with 'id', returns 0. EXAMPLE # This searches for the buffer whose identifier is 'id'. int desired_id; int id; id = currbuf(); while (id != desired_id) id = next_buffer(id); Macro Functions - Buffer Services Chapter 14 Page 4 ME USERS MANUAL setcurrbuf(id) int id; DESCRIPTION Setcurrbuf() makes the buffer whose identifier is ID the current buffer. ARGUMENTS The identifier of the desired buffer. RETURNS The ID of the buffer is returned if successful. 0 is returned if the function failed. EXAMPLE show_buffer(id) int id; DESCRIPTION Show_buffer() makes the buffer with identifier 'id' the current buffer. If there is no window associated with the buffer, then a window is created. ARGUMENTS The integer identifier of the buffer to be shown. RETURNS The identifier of the buffer if successful, 0 if not. EXAMPLE int id; if ((id = find_buffer("foo.c")) > 0) show_buffer(id); Macro Functions - Buffer Services Chapter 14 Page 5 ME USERS MANUAL PRIMITIVE FUNCTIONS The following list of functions can be used in the macro programming language of the editor. For each function, the name and optional aruments are given, along with a brief description of the function, a description of the arguments and return value, and an example. We realize that you may need to have a primitive which doesn't exist. If we were to include every primitive which every user wanted, then the number of primitives would become unwieldly. Please let us know if you think that a certain primitive is absolutely imperative. assign_key(macroname, key) string macroname; int key; DESCRIPTION Assigns the keystroke specified in "key" to the macro specified in "macroname". Whenever that keystroke is pressed, the named macro will be executed. ARGUMENTS "Macroname" is the name of the macro to be assigned, in quotes. "Key" is the value of the key. If you are not sure what the value of a key is, use the <TEST KEY> command (ALT F10) in the editor. RETURNS Returns the second argument if successful, 0 if not. EXAMPLE init() { ..... assign_key("justify", 10); ..... } justify() { ..... } Macro Functions - Primitives Chapter 15 Page 1 ME USERS MANUAL The justify() macro is assigned to CTRL-J key (ASCII value 10). The init() procedure is executed only once, when the macro file is initially loaded into the editor. From now on, any time you press the CTRL_J key, the justify() macro will be done. atoi(str) string str; DESCRIPTION Atoi() scans str for an integer and returns the value of the integer. If the first character of the string is not a number (or a valid numerical prefix, like '+' or '-'), then the ASCII value of the first character is returned. ARGUMENTS Str is a string which should contain a numerical string starting at the first character. RETURNS The integer value extracted from str. EXAMPLE string s; int n; s = "123"; n = atoi(s); /* n is 123 */ s = "ABC"; n = atoi(s); /* n is 65, the ASCII value of 'A' */ bell() DESCRIPTION Bell() sounds a tone on the PC. This is useful for alerting users Macro Functions - Primitives Chapter 15 Page 2 ME USERS MANUAL to a prompt, error condition, etc. ARGUMENTS None. RETURNS Nothing EXAMPLES if (x < 0) { bell(); message("Number must be positive"); } buffer_modified() DESCRIPTION Used to tell if the current buffer has been modified since it was used this editing session. ARGUMENTS None. RETURNS Non-zero if the buffer has been modified, 0 if not. EXAMPLES if (buffer_modified()) { bell(); message("Buffer modified - quit anyway (y/n)"); if ((c = get_tty_char()) == 'y' || c == 'Y') delete_buffer(currbuf()); } Macro Functions - Primitives Chapter 15 Page 3 ME USERS MANUAL chr(c) int c; DESCRIPTION Chr() takes the integer in c and returns a one-character string with c as the first character. C should be between 0 and 255. This function should be used when you perform certain operations between strings, and one of the strings is an integer. ARGUMENTS 'C' is an integer between 0 and 255. RETURNS The one-character string with the ASCII value of 'c' as the first character. EXAMPLES int c; c = 's'; str = "do"; str = strcat(str, chr(c)); /* str will be "dos" */ Note that if chr() wasn't used, then str would have been "do115", since c is converted to a numeric string. The general rule is that if a function expects a string as an argument, and you send it an integer, then the integer will be converted to a numeric string. clear_positions() DESCRIPTION Clear_positions() clears the stack of saved positions. See the save_position() and restore_position() functions. ARGUMENTS None. Macro Functions - Primitives Chapter 15 Page 4 ME USERS MANUAL RETURNS Nothing. EXAMPLES See the incremental search macro included with the editor. command(func) int func; DESCRIPTION Command() takes a keystroke whose value is the integer 'func' and calls the editor's command dispatcher to execute the command. If you have a routine which dispatches on user keystrokes, and you need to invoke the default processing on the keys you aren't interested in, this function can be used as a default command dispatcher. (See example below). ARGUMENTS 'Func' is the integer keystroke between 0 and 255. RETURNS Nothing. EXAMPLES if ((c = get_tty_char()) == 145) .... else if (c == 203) .... else command(c); /* call the editor to execute the keystroke */ currchar() DESCRIPTION Returns the character under the cursor. Macro Functions - Primitives Chapter 15 Page 5 ME USERS MANUAL ARGUMENTS None. RETURNS An integer representing the ASCII value of the character. EXAMPLE /* advance cursor forward until a non-blank character is reached */ while (!iseof() && currchar() == ' ') right(); currcol() DESCRIPTION Returns the value of the column which the cursor is on. ARGUMENTS None. RETURNS An integer between 1 and 32767. EXAMPLE int col; col = currcol(); currline() DESCRIPTION Returns the text of the current line (the line where the cursor is). Macro Functions - Primitives Chapter 15 Page 6 ME USERS MANUAL ARGUMENTS None. currlinenum() DESCRIPTION Returns the line number of the current line. ARGUMENTS None. RETURNS A number between 1 and the last line of the file. EXAMPLE /* THIS CODE DELETES ALL LINES FROM THE BEGINNING OF THE FILE */ /* UNTIL (BUT NOT INCLUDING) THE CURRENT LINE */ del_from_bof() { int i, endline; endline = currlinenum(); goline(1); for (i = 1; i < endline; i = i + 1) delline(); } filename() Macro Functions - Primitives Chapter 15 Page 7 ME USERS MANUAL DESCRPTION Returns the filename of the file currently being edited. ARGUMENTS None. RETURNS A string result. get_tty_char() DESCRIPTION Waits for the user to press a key, and returns the value of that keystroke. ARGUMENTS None. RETURNS The integer value of the keystroke. EXAMPLE message("Do you really want to do this?"); if ((c = get_tty_char()) == 'Y' || c == 'y') doit(); get_tty_str(prompt) string prompt; DESCRIPTION Displays the prompt on the status line, then waits for the user to enter a string (ended by hitting RETURN). In addition to this function being useful for getting information from the user, it is also useful for debugging your macros (see below). Macro Functions - Primitives Chapter 15 Page 8 ME USERS MANUAL ARGUMENTS The text of the prompt. RETURNS The string that the user typed in. EXAMPLE int n; string foo; ....... /* display info, and wait for user to acknowledge */ foo = get_tty_str(sprintf("The value of n is %d", n)); index(str, pat) string str; string pat; DESCRIPTION Locates the first occurence of the string 'pat' within the string 'str'. ARGUMENTS 'Str' is the string to search through. 'Pat' is the string to search for. The length of this string should be less than or equal to the length of 'str'. RETURNS The position in 'str' where the first occurence of 'pat' is found. This position is between 1 and the length of 'str'. If 'pat' is not found, 0 is returned. EXAMPLE /* The following piece of code changes all occurences of "Mrs." to "Miss" on the current line. */ int savecol, i, j; Macro Functions - Primitives Chapter 15 Page 9 ME USERS MANUAL savecol = currcol(); /* save the current cursor position */ while ((i = index(currline(), "Mrs.")) > 0) { setcol(i+1); /* move to the "r" in "Mrs." */ insert("iss"); /* add "iss" to the line */ for (j = 1; j <= 3; j = j + 1) /* get rid of the "rs." */ delchar(); } setcol(savecol); /* return to the old cursor position */ insert(str) string str; DESCRIPTION Insert() takes the string 'str' and inserts it at the current cursor position. This has the same effect as if you had typed the characters in the string on the keyboard. Characters to the right of the inserted string will be pushed over. ARGUMENTS Str is the string which will be inserted. If you have an integer variable between 0 and 255, and you would like to insert it, then you must use the chr() function. RETURNS Nothing. is_bof() DESCRIPTION Returns 1 if the cursor is at the first character of the file, 0 if not. ARGUMENTS None. Macro Functions - Primitives Chapter 15 Page 10 ME USERS MANUAL RETURNS See above. is_bol() DESCRIPTION Returns 1 if the cursor is at the beginning of the current line, 0 if not. ARGUMENTS None. RETURNS See above. is_eof() DESCRIPTION Returns 1 if the cursor is just past the last character of the file, 0 if not. ARGUMENTS None. RETURNS See above. is_eol() DESCRIPTION Returns 1 if the cursor is past the last character of the current line, 0 if Macro Functions - Primitives Chapter 15 Page 11 ME USERS MANUAL not. ARGUMENTS None. RETURNS See above. is_linemarked() DESCRIPTION Is_linemarked() is used to tell if the current line is marked. A line can be marked with the command (ALT F7), or the command (ALT F8). ARGUMENTS None. RETURNS Returns 1 if the current line is marked, 0 if not. EXAMPLE /* This loop changes all marked lines to uppercase characters. Assume that the user wrote a routine called uppercase() which changes the current line to all uppercase. */ gobof(); /* move to the first line */ while (currlinenum() <= lastlinenum()) { if (is_linemarked()) uppercase(); /* assume this is a user written routine */ down(); } As an aside, the above loop would run faster if we kept a variable as the line counter, like : Macro Functions - Primitives Chapter 15 Page 12 ME USERS MANUAL i = 1; last = lastlinenum(); while (i <= last) ..... i = i + 1; itoa(n) int n; DESCRIPTION Converts the integer 'n' to a string. ARGUMENTS 'N' is the number to convert. The value of 'n' is not changed. RETURNS The string which represents the number. This string is dynamically allocated. EXAMPLE string linenum; linenum = itoa(currlinenum()); message(strcat("We are on line ", linenum)); lastlinenum() DESCRIPTION Returns the line number of the last line in the current buffer. ARGUMENTS None. RETURNS Macro Functions - Primitives Chapter 15 Page 13 ME USERS MANUAL An integer. EXAMPLE /* The following statement moves the currentline to the last line */ goline(lastlinenum()); ltrim(str) string str; DESCRIPTION Ltrim() trims all leading blanks from the string 'str'. ARGUMENTS 'Str' is the string to trim. RETURNS Nothing. marked_col() DESCRIPTION If the mark is set, returns the column which the marker is on. Otherwise, returns 0. ARGUMENTS None. RETURNS See above. Macro Functions - Primitives Chapter 15 Page 14 ME USERS MANUAL marked_line() DESCRIPTION If the mark is set, returns the line number of the line which the marker is on. Otherwise, returns 0. ARGUMENTS None. RETURNS See above. message(str) string str; DESCRIPTION Displays the string 'str' on the status line. ARGUMENTS The message to print. RETURNS Nothing. repstr(str, n) string str; int n; DESCRIPTION Replicates string 'str' 'n' times. String 'str' is NOT altered. ARGUMENTS Macro Functions - Primitives Chapter 15 Page 15 ME USERS MANUAL String 'str' contains the string to replicate. 'N' is an integer which is the number of times to replicate the string. RETURNS Returns the new string. EXAMPLE /* This statement inserts a slash, followed by 30 asterisks, */ /* followed by a slash, into the file. */ insert(strcat( "/", strcat(repstr("*", 30), "/") )); restore_position() DESCRIPTION Restore_position() sets the cursor to the last position that was saved on the position stack. This position will be removed from the stack. See the save_position() function for more information. ARGUMENTS None. RETURNS Nothing. EXAMPLES save_position(); goline(200); insert("foo"); restore_position(); See also the incremental search macro included with the editor. Macro Functions - Primitives Chapter 15 Page 16 ME USERS MANUAL rtrim(str) string str; DESCRIPTION Rtrim() trims all trailing blanks from the string 'str'. ARGUMENTS 'Str' is the string to trim. RETURNS Nothing. save_position() DESCRIPTION Save_position() places the current cursor position on the position stack. The position stack records the current line and the current column where the cursor is. To return to a previous position, use the restore_position function. ARGUMENTS None. RETURNS Nothing. EXAMPLES save_position(); goline(200); insert("foo"); restore_position(); See also the incremental search macro included with the editor. Macro Functions - Primitives Chapter 15 Page 17 ME USERS MANUAL setbufnum(n) int n; DESCRIPTION Changes the current pick buffer number to number 'n'. ARGUMENTS The integer 'n' must be between 0 and 9. 0 is the default buffer that the editor initially uses for all cut and paste operations. RETURNS 1 if successful, 0 if not. setcol(col) int col; DESCRIPTION Move the cursor to column 'col' on the current line. ARGUMENTS 'Col' is the integer column to move to. RETURNS The column number if successful, 0 if not. EXAMPLE /* This function simulates the <GOTO END OF LINE> key. */ go_eol() { setcol( strlen(currline()) + 1 ); } Macro Functions - Primitives Chapter 15 Page 18 ME USERS MANUAL setprompt(n) int n; DESCRIPTION Enables or disables the prompting that the editor uses for certain commands. ARGUMENTS 0 if prompts should be turned off, a non-zero if they should be turned on. RETURNS Nothing. EXAMPLE setprompt(0); sprintf(format[, args]) string format; DESCRIPTION Formats a string according to the format string parameter. The for- mat string 'format' consists of a combination of characters to print and format specifiers. Each format specifier describes a way to print out a certain argument. The format specifiers currently accepted are %d decimal integer %s string ARGUMENTS 'Format' is the format string. The format string consists of a combination of literal characters and format specifiers. 'Args' is a list of 0 or more arguments. Argument i corresponds to format specifier i in the format string. RETURNS The formatted string. Macro Functions - Primitives Chapter 15 Page 19 ME USERS MANUAL EXAMPLE string foo; foo = get_tty_str(sprintf("Col %d Line %d of %d", currcol(), currline(), lastline())); strcat(s1, s2) string s1, s2; DESCRIPTION Appends string 's2' to the end of string 's1'. ARGUMENTS 'S1' and 's2' must both be strings. If either are integers, then they are converted to strings before the append takes place. RETURNS Returns 's1', which contains the appended result. EXAMPLE insert(strcat("The current buffer name is ", filename())); strlen(str) string str; DESCRIPTION Returns the length of the string in 'str'. ARGUMENTS 'Str' is the string to examine. RETURNS Macro Functions - Primitives Chapter 15 Page 20 ME USERS MANUAL An integer length >= 0. substr(str, pos, len) string str; int pos; int len; DESCRIPTION Extracts 'len' characters from the string in 'str' starting at position 'pos'. ARGUMENTS 'Str' is the string to examine. 'Pos' is the position in 'str' to start at. Pos should be a number between 1 and the length of the string. 'Len' is the number of characters to extract. RETURNS The string extracted. EXAMPLE dotpos = index(filename(), "."); if (dotpos > 0) root = substr(filename(), 1, dotpos - 1); else root = filename(); tabs(str) string str; DESCRIPTION Tabs() is used to set the tab stops. ARGUMENTS Str is a string which contains a list of tab stops. The string consists a numbers separated by one or more blanks. Macro Functions - Primitives Chapter 15 Page 21 ME USERS MANUAL RETURNS Nothing. EXAMPLE tabs("10 16 25 36"); ungetc(c) int c; DESCRIPTION Ungetc() pushes the character 'c' back onto the input stream. The next time that the editor goes to read a character, 'c' will be read. There is no limit as to the number of characters you can push back. ARGUMENTS 'C' is the character to push back. It can be the values 0 through 255. RETURNS Nothing. Macro Functions - Primitives Chapter 15 Page 22 ME USERS MANUAL REMAPPING THE KEYBOARD A character that you type at the keyboard can take on 256 dif- ferent values, from 0 to 255. On the IBM PC, the ASCII characters are numbered from 0 to 127, and the IBM extended characters are numbered from 128 to 255. All of the function key combinations and numeric keypad combinations fall into the extended character set. The editor has an internal table which is used to translate one value into another. This internal table is 256 bytes long, with byte 0 holding the translation value for keystroke value 0, byte 1 holding the value for keystroke 1, etc. The default values for this table in- dicate no translations (ie keystroke number n is translated into value n.) AN EXAMPLE OF REMAPPING As an example where translation may be desirable, let's consider a very simple remapping of the keyboard. The command that is associated with the F1 function key is <DELETE LINE>. Let's say that you would like the <HELP> function to be assigned to the F1 key, and the <DELETE LINE> function assigned to the <ALT> D key. Currently, the <HELP> function is assigned to the <ALT> H key. To find out what keystroke values the F1, <ALT> D and <ALT> H keys produce, use the <TEST KEYS> command from the editor. This command is done by pressing the ALT F10 key. The <TEST KEYS> com- mand prompts you for a keystroke, and then prints the value that the keystroke produced. After invoking the <TEST KEYS> command, we find that the following values are produced : F1 187 ALT D 60 ALT H 163 What we would like to do is have the F1 key "generate" the <ALT> H keystroke, and have the <ALT> D key "generate" the F1 value. In other words, we would like to fool the editor into thinking that when the F1 key is pressed, the <ALT> H key was really pressed. To effect these changes, we would like to put the value 163 into byte 187 of the table, and put value 187 into byte 160 of the table. How can we do this without going altering the editor's executable file? Remapping the Keyboard Appendix A Page 1 ME USERS MANUAL THE KEYTABLE FILE The file which holds the keystroke translation values is called "KEYTABLE.ME". When the editor starts up, it will first look in your current subdirectory for the KEYTABLE.ME file. If the editor doesn't find it there, then the editor will search the directories listed in your DOS search path. If this file still isn't found, then the in- ternal table is filled sequentially with the values 0 through 255. This means that no remapping will be performed. The KEYTABLE.ME file contains one or more tables which are 256 bytes long, with byte i corresponding to keystroke i. The editor comes with a default KEYTABLE.ME file. It also comes with several utilities to create and alter the KEYTABLE.ME file. The first utility we will talk about is called KEYCOMP.EXE. This program reads a keystroke configuration file and generates a KEYTABLE.ME file from it. A keystroke configuration file contains a list of keystrokes and their corresponding values. Each line of the keystroke configuration file has the form : key=func The "key" can be a decimal number, a single character between single quotes, ^char (a control character between 0 and 31), F# where '#' is a number between 1 and 10 (this is a normal function key), AF# (ALT function key), SF# (SHIFT function key), CF# (CTRL function key), or @char (ALT character key). "Func" is a number representing the value that the key produces. Here are some examples : 120=122 (the key with the value 120 produces 122) '#'=289 (a pound sign produces 289) ^C=14 (CTRL C produces 14) F1=160 (F1 produces 160) @A=198 (ALT A produces 198) SF9=130 (SHIFT f9 produces 130) Any keystrokes which aren't mentioned in the configuration file will just be translated into themselves. To run the keystroke compiler, type the command Remapping the Keyboard Appendix A Page 2 ME USERS MANUAL KEYCOMP filename where filename is the name of the keystroke configuration file. If everything goes well, the KEYTABLE.ME file will be created. You can not TYPE out the KEYTABLE.ME file since it contains binary data. However, you can examine it with various disk utilities (such as the NORTON Utilities). The second utility is called KEYCONF.EXE. This program generates a default keystroke configuration file. There are 256 lines in the generated file. The file looks like this : 0=0 1=1 255=255 The output from this program is written to the screen. You can redirect the output to a file be giving the command : KEYCONF > keyfile (or any other name) Once this sample keystroke configuration file is generated, you can alter it with any text editor, and then compile it using KEYCOMP.EXE. The third utility is called KEYTEST.EXE. This program waits for you to type a keystroke, and then prints out the value of that keystroke. Hitting the <ESC> key will stop the program. This program is also simulated by the <TEST KEYS> command of the editor. PREFIXES Some people would like to have the editor emulate their favorite word processor, and hence, will make key maps which map the function keys of the editor into the keystrokes that their word processor requires. Some word processors use a two-keystroke sequence to generate a command. One of the most well-known examples of this is WordStar (WordStar is a trademark of MicroPro Inc.). For instance, the keystroke sequence CTRL K D is used to exit WordStar. You can specify prefixes in the keystroke redefinition file which is compiled by the KEYCOMP.EXE program. A prefix line is of the form : PREFIX <keystroke> Remapping the Keyboard Appendix A Page 3 ME USERS MANUAL The PREFIX statement creates a 256 byte table which contains the commands generated by the second key of the sequence. As an example, you press CTRL D right now to exit the editor. CTRL D generates a keystroke value of 4. If you would like to use the CTRL K D keystroke combination to exit the editor instead, then your keystroke file should contain a line like this : PREFIX ^K ..... list of CTRL K commands D=4 ...... A prefix command table ends when the compiler encounters another PREFIX statement, or when the compiler reaches the end of the redefinition file. All of the prefix definitions should come after the definitions for the main table. For a good example, examine the WSKEYS file which comes with the keyboard remapping facility. This file contains the keystroke definitions to configure the keyboard like WordStar. SOURCE FILES Included in the editor package are the source files to the above mentioned utilities. We request that if you improve these utilities, that you send the source back to us so that we can incorporate it in future releases. In exchange, you will receive a free copy of the next release of the editor. Remapping the Keyboard Appendix A Page 4 ME USERS MANUAL THE CTAGS UTILITY If you are working on a large project, your source code most likely resides in several different files. The CTAGS utility, originated in Berkeley UNIX (UNIX is a trademark of AT&T), helps you create a little order out of your C files. The CTAGS utility keeps a record of the name of each function declared in your source files, and which file the function occurs in. By using the CTAGS utility in conjunction with the <GOTO FUNCTION> command (the CTRL T key), you can specify the name of a function and have the editor move you to the point of the function definition. As mentioned above, the CTAGS utility creates a file called "TAGS" which resides in your current directory. The TAGS file has a list of all of the functions that you declared in specific source code files, the full name of the file in which each function was declared, and a pattern to be used by the the editor's <SEARCH> command. To invoke the CTAGS utility, use this command from the DOS prompt: CTAGS filename1 [filename2...] The file name can have wild-card characters in it. To create a TAGS file for all of the source files in your current directory, use the command CTAGS *.c When you use the <GOTO FUNCTION> command (the CTRL T key), you are asked for the name of the function that you would like to go to. The <GOTO FUNCTION> command then reads the TAGS file, and attempts to find a line in the TAGS file which contains the name of the function you want to visit. If it's successful, another window will open up on the screen, and the cursor will be positioned on that function definition. In order to keep the TAGS file up-to-date, you may want to invoke the CTAGS utility at periodic intervals. If you delete a function or move a function from one file to another without updating the CTAGS file, then the <GOTO FUNCTION> command won't be able to locate the function. The CTAGS Utility Appendix B Page 1